<!DOCTYPE html>

<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
    <title>State Management - Raxan User Guide</title>
    <link href="../raxan/ui/css/master.css" rel="stylesheet" type="text/css" />
    <!--[if lt IE 8]> <link rel="stylesheet" href="../raxan/ui/css/master.ie.css" type="text/css"><![endif]-->
    <link href="../raxan/ui/css/default/theme.css" rel="stylesheet" type="text/css" />
    <link href="style.css" rel="stylesheet" type="text/css" />
    <link href="highlight/styles/default.css" rel="stylesheet" type="text/css" />
    <script type="text/javascript" src="highlight/highlight.js"></script>
    <script type="text/javascript">
        <!--
        hljs.initHighlightingOnLoad('javascript','html','php','css');
        //-->
    </script>
    <!--[if lt IE 7]>
        <style type="text/css"> form input.textbox { height: 26px; }</style>
    <![endif]-->
</head>

<body>
    <div class="container">
        <div id="header" class="rax-header-pal rax-metalic">
            <h2 class="ltm bottom c14">Raxan User Guide</h2>
            <ul>
                <li><a href="../../index.html">Home</a></li>
                <li><a href="index.html">Overview</a></li>
                <li><a href="features.html">Features</a></li>
                <li><a href="table-of-contents.html" title="Table of Content">Contents</a></li>
                <li><a href="../examples">Examples</a></li>
            </ul>
            <ul class="search">
                <li>
                    <form class="tpm c9" name="form1" action="../tools/search.php" method="get">
                        <input class="c6 textbox round left" placeholder="Search" type="text" name="q" value="" title="Search User Guide"  />
                        <input class="c2 button round left ltm" type="submit" value="Go" />
                    </form>
                </li>
            </ul>

        </div>
        <hr class="space"/>
        <div class="master-content-wrapper">
            <div class="container prepend-top c48 master-content"><h2>State &amp; Session Management</h2>

<p>Preserving the state of an element can be useful when you want to retain the special attributes and content
across multiple web pages or during full page post back.</p>

<p>To preserve the state of an element you will need to add the "<strong>xt-preservestate</strong>" extended attribute to the element, or call
the RaxanElement->preserveState() method. States can be either local to a web page or to the current user session.</p>

<p>Format:</p>

<pre><code>xt-preservestate = "local | session"
</code></pre>

<ul>
<li>local - (Default) Preserves state during page post back.</li>
<li>session - Preserves state until the currently user session has been terminated ends</li>
</ul>

<p>Here's an example of a locally preserved element:</p>

<pre><code class="php">&lt;?php
    require_once('raxan/pdi/autostart.php');

    class NewPage extends RaxanWebPage {

        // change paragraph color
        protected function changeColor($e) {
            $this-&gt;myid-&gt;css('background','#ffcc00');
        }

        protected function reloadPage($e) {
            // do something;
        }
    }

?&gt;

&lt;p id="myid" xt-preservestate="local"&gt;Lorem ipsum cu nam impedit efficiantur&lt;/p&gt;
&lt;a href="#" xt-bind="click,changeColor"&gt;Click to Change Color&lt;/a&gt;&lt;br /&gt;&lt;br /&gt;
&lt;a href="#" xt-bind="click,reloadPage"&gt;Click to Reload Page&lt;/a&gt;
</code></pre>

<p>When the user clicks on the link to change the background color, the of the &lt;p&gt; tag, the framework records the changes and
preserve the state of the element during post backs.</p>

<p>When the "Reload Page" link is clicked the &lt;p&gt; tag element will be display with the new background color.</p>

<p>The "session state" is very similar to "local state" with the exception that the state is preserved for the duration of the user session.
This means that an element can maintain it's state across web pages.</p>

<p>If we were to modify the above example and set <strong>xtpreservestate="session"</strong>, then the framework will preserve and display the last saved state
of <strong>myid</strong> across multiple web pages.</p>

<pre><code class="php">&lt;?php 
    require_once('raxan/pdi/autostart.php');

    class AnotherPage extends RaxanWebPage {

        protected function _load() {
            // code here
        }

    }

?&gt;

&lt;p id="myid" xt-preservestate="session"&gt;Lorem ipsum cu nam impedit efficiantur&lt;/p&gt;
</code></pre>

<h3>Persisting Page/Session Data</h3>

<p>Raxan provides two methods for persisting data: The page and session data() methods</p>

<p>The page data method allow developers to persist serializable objects and variables during a page "POST" request. This data is only removed
when the page is called via a "GET" request.</p>

<p>To do this use the <strong>$this->data()</strong> method as shown below:</p>

<pre><code class="php">&lt;?php
    require_once('raxan/pdi/autostart.php');

    class NewPage extends RaxanWebPage {

        protected $cnt = 0;

        protected function _load() {
            $this-&gt;cnt = $this-&gt;data('my-counter'); // get my-counter data value
        }

        protected function _prerender() {
            $this-&gt;counter-&gt;text('Click Me : '.$this-&gt;cnt );
        }

        protected function countUp($e) {
            $this-&gt;cnt++;
            $this-&gt;data('my-counter',$this-&gt;cnt); // save my-counter data value
        }

        protected function callback($e) {
            // do something;
        }
    }
?&gt;

&lt;a id="counter" href="#" xt-bind="click,countUp"&gt;Click Me&lt;/a&gt;&amp;nbsp;|&amp;nbsp;
&lt;a href="#" xt-bind="click,callback"&gt;Post Page&lt;/a&gt;
</code></pre>

<p>The session data method allow developers to persist serializable objects and variables for the duration of the user session. This means that
variables will remain persisted until the session is destroyed.</p>

<p>To do this use the <strong>$this->Raxan->data()</strong> method as shown below:</p>

<pre><code class="php">&lt;?php
    require_once('raxan/pdi/autostart.php');

    class NewPage extends RaxanWebPage {

        protected $cnt = 0;

        protected function _load() {
            $this-&gt;cnt = &amp; $this-&gt;Raxan-&gt;data('my-counter',0,true); // get reference my-counter data value
        }

        protected function _prerender() {
            if ($this-&gt;cnt)
                $this-&gt;counter-&gt;text('Click Me : '.$this-&gt;cnt );
        }

        protected function countUp($e) {
            $this-&gt;cnt++;
        }

        protected function callback($e) {
            // do something;
        }

        protected function resetCounter($e) {
            $this-&gt;cnt = 0;
            $this-&gt;Raxan-&gt;removeData('my-counter'); // remove counter value
        }
    }
?&gt;

&lt;a id="counter" href="#" xt-bind="click,countUp"&gt;Click Me&lt;/a&gt;&amp;nbsp;|&amp;nbsp;
&lt;a href="#" xt-bind="click,callback"&gt;Post Page&lt;/a&gt;&amp;nbsp;|&amp;nbsp;
&lt;a href="#" xt-bind="click,resetCounter"&gt;Reset Counter&lt;/a&gt;
</code></pre>

<p>To remove page or session data you can use the <strong>$this->removeData()</strong> or <strong>$this->Raxan->removeData()</strong> method.</p>

<h4><strong>Storing values inside a Data Bank</strong></h4>

<p>In addition to the above you can also use the <strong>dataBank()</strong> method to set or retrieve data values from a data bank that is stored within the
current user session:</p>

<pre><code class="php">&lt;?php
    protected function saveEntry($e) {
        $title = $e-&gt;textVal();
        // store title inside the TopMovie data bank
        $this-&gt;Raxan-&gt;dataBank('TopMovie','dvd-pop-title',$title);
    }

    protected function loadEntry($e) {
        // retrieves dvd-pop-title from TopMovie data bank
        $title = $this-&gt;Raxan-&gt;dataBank('TopMovie','dvd-pop-title');
        $this-&gt;txtPopTitle-&gt;text($title);

        // retrieves the entire data bank array
        $movies = &amp; $this-&gt;Raxan-&gt;dataBank('TopMovie');
    }
?&gt;
</code></pre>

<p>To remove an entry from the data bank use the <strong>removeDataBank()</strong> method as shown below:</p>

<pre><code class="php">&lt;?php
    protected function removeEntry() {
        // remove dvd-pop-title form TopMovie data bank
        $this-&gt;Raxan-&gt;removeDataBank('TopMovie','dvd-pop-title');

        // remove the TopMovie data bank
        $this-&gt;Raxan-&gt;removeDataBank('TopMovie');
    }
?&gt;
</code></pre>

<h3>Creating a Custom Page/Session Storage Class</h3>

<p>There are two data storage classes available within the framework. These classes are responsible for storing and retrieving page/session data:</p>

<ul>
<li>RaxanPageStorage -  Handles page data storage</li>
<li>RaxanSessionStorage - Handles session data storage</li>
</ul>

<p>The RaxanSessionStorage class uses the PHP session object to store data values. If no current PHP session exists then one will be created.
If a PHP session already exists, then it will be used but the session name and timeout properties will not be managed via the framework.</p>

<p>The RaxanPageStorage class uses Raxan's data storage methods to store and retrieve page data. This means that page data will also be storeg in the
current user session. The only difference is that the data will be reset on first load if the <strong>resetDataOnFirstLoad</strong> property is set to true.
The value for the page <strong>resetDataOnFirstLoad</strong> property defaults to true.</p>

<p>To prevent the page data from being reset on first load, set resetDataOnFirstLoad to false or use the storeName() method to change the data store 
name for the current page:</p>

<pre><code class="php">&lt;?php

    class NewPage extends RaxanWebPage {
        protected function _config() {
            $this-&gt;resetDataOnFirstLoad = false;
            $this-&gt;storeName('my-data-store-name');
        }

        protected function _load() {
            // do something here
        }
    }

?&gt;
</code></pre>

<p>To create your own data storage you can extend the RaxanDatastorage class as shown below:</p>

<pre><code class="php">&lt;?php
    class MyStorageClass extends RaxanDatastorage {
        protected function _init() {
            $id = $this-&gt;id;
            // code to initialize array $store here
            $this-&gt;store = $store; // set storage array
        }

        protected function _reset() {
            $id = $this-&gt;id;
            // code to reset array $store here
            $this-&gt;store = $store; // set new array
        }

        protected function _save() {
            $id = $this-&gt;id;
            $store = $this-&gt;store;
            // code to save $store here
        }

    }

?&gt;
</code></pre>

<p>To register your new data storage class you can the "<strong>session.data.storage</strong>", "<strong>page.data.session</strong>" config options:</p>

<pre><code class="php">&lt;?php

    Raxan::config('session.data.storage', 'MyStorageClass') ; // set default session storage class
    Raxan::config('page.data.storage', 'MyStorageClass') ;    // set default page storage class

?&gt;
</code></pre>

<p>You can also use the <strong>dataStorage()</strong> method as show below:</p>

<pre><code class="php"> &lt;?php

    protected function _config() {

        // code to generate/retrieve unique page or session $id here

        // register session data storage object
        $st = new MyStorageClass($uniqueId);
        $this-&gt;Raxan-&gt;dataStore($st);

        // register page data storage object
        // $this-&gt;dataStore($st);
    }

 ?&gt;
</code></pre>

<p>To learn more about the data APIs visit <a href="RaxanWebPage.html#data">RaxanWebPage::data</a>, <a href="Raxan.html#data">Raxan::data()</a> and <a href="Raxan.html#dataBank">Raxan::dataBank()</a></p>

<h3>Preserving Form Content</h3>

<p>In addition to preserving the state of an element within the page, you can also preserve the content of a web form during post back by setting
<strong>preserveFormContent</strong> property to true.</p>

<p>By enabling this feature you can eliminate the need to manually sanitize and update form elements with values that are submitted from the client:</p>

<pre><code class="php">&lt;?php

    class NewPage extends RaxanWebPage {
        protected function _config() {
            $this-&gt;preserveFormContent = true;
        }

        protected function _load() {
            // do something here
        }
    }
?&gt;

&lt;form name="form1" action="" method="post"&gt;
    &lt;input type="text" name="text1" id="text1" value="I am a textbox" /&gt;
    &lt;input type="submit" name="submit1" id="submit1" value="Submit" /&gt;
&lt;/form&gt;
</code></pre>

<p>When the "submit" button is clicked the content the current value text box will be redisplayed after a full page post back.</p>

<p>If an element is marked as <strong>readonly</strong> or <strong>disabled</strong> its content will not be updated:</p>

<pre><code class="php">&lt;?php

    class NewPage extends RaxanWebPage {
        protected function _config() {
            $this-&gt;preserveFormContent = true;
        }

        protected function _load() {
            // do something here
        }
    }
?&gt;

&lt;form name="form1" action="" method="post"&gt;
    &lt;input type="text" name="text1" id="text1" value="I am a readonly textbox" readonly /&gt;
    &lt;input type="submit" name="submit1" id="submit1" value="Submit" /&gt;
&lt;/form&gt;
</code></pre>

<p>By using the "preserve form content" feature you can save time and reduce the code size of the application.</p>

<hr class="clear" />

<p align="right">Up Next: <a href="plugins.html" title="Data Sanitization">Web Page Plugins</a> </p>
</div>
            
            <div id="footer" class="container c48 rax-active-pal round rax-glossy">
                <ul class="clearfix">
                    <li><a href="index.html">Overview</a></li>
                    <li><a href="features.html">Features</a></li>
                    <li><a href="new-features.html">What's new</a></li>
                    <li><a href="table-of-contents.html" title="Table of Content">Contents</a></li>
                    <li><a href="../examples">Examples</a></li>
                </ul>
            </div>
        </div>
    </div>
</body>

</html>

